package com.kun.video.context.factory;

import com.kun.video.AbstractApplication;

import java.net.URL;
import java.util.List;
import java.util.function.Function;

/**
 * 单例上下文工厂接口
 *
 * <p>用于管理应用程序全局单例对象的生命周期和访问，提供键值对形式的上下文存储能力。
 * 实现类应确保线程安全及单例特性。</p>
 *
 * @author gzc
 * @since 2025/2/1
 **/
public interface SingletonContextFactory<K, V> {
    /**
     * 对象初始化排序，序号越小优先级越高
     *
     * @return 序号
     */
    default int order() {
        return 0;
    }

    /**
     * 初始化工厂
     *
     * @param packagePathList 指定扫描的包路径列表
     * @param loader          应用程序加载器类，用于确定类加载路径
     * @param loadFunction    资源加载函数，输入键（如资源路径），返回对应的URL资源
     */
    void init(List<String> packagePathList,
              Class<? extends AbstractApplication> loader,
              Function<String, URL> loadFunction);

    /**
     * 根据键获取上下文中的值
     *
     * @param key 键对象，不可为null
     * @return 与键关联的值，若不存在则返回null
     * @throws IllegalArgumentException 如果键为null或类型不匹配
     */
    V get(K key);

    /**
     * 将键值对存储到上下文中
     *
     * @param key   键对象，不可为null
     * @param value 值对象，可为null（具体实现类决定是否支持）
     * @throws IllegalArgumentException 如果键为null或类型不匹配
     */
    void put(K key, V value);

    /**
     * 从上下文中移除指定键的条目
     *
     * @param key 要移除的键，不可为null
     * @throws IllegalArgumentException 如果键为null或类型不匹配
     */
    void remove(K key);

    /**
     * 销毁上下文
     *
     * <p>释放所有资源并清理存储数据，调用后上下文不可再使用。</p>
     */
    void destroy();
}